<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Mapping users and groups to roles | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'mapping-roles.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/mapping-roles.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/mapping-roles.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/mapping-roles.html" rel="nofollow" target="_blank">../en/mapping-roles.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="secure-cluster.html">Secure a cluster</a></span>
»
<span class="breadcrumb-link"><a href="authorization.html">User authorization</a></span>
»
<span class="breadcrumb-node">Mapping users and groups to roles</span>
</div>
<div class="navheader">
<span class="prev">
<a href="securing-aliases.html">« Granting privileges for indices and aliases</a>
</span>
<span class="next">
<a href="field-and-document-access-control.html">Setting up field and document level security »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="mapping-roles"></a>Mapping users and groups to roles<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>
<p>If you authenticate users with the <code class="literal">native</code> or <code class="literal">file</code> realms, you can manage
role assignment by using the <a class="xref" href="native-realm.html#managing-native-users" title="Managing native users">User Management APIs</a> or
the <a href="users-command.html" class="ulink" target="_top">users</a> command-line tool respectively.</p>
<p>For other types of realms, you must create <em>role-mappings</em> that define which
roles should be assigned to each user based on their username, groups, or
other metadata.</p>
<p>You can define role-mappings via an
<a class="xref" href="mapping-roles.html#mapping-roles-api" title="Using the role mapping API">API</a> or manage them through <a class="xref" href="mapping-roles.html#mapping-roles-file" title="Using role mapping files">files</a>.
These two sources of role-mapping are combined inside of the Elasticsearch
security features, so it is
possible for a single user to have some roles that have been mapped through
the API, and other roles that are mapped through files.</p>
<p>When you use role-mappings, you assign existing roles to users.
The available roles should either be added using the
<a href="security-api.html#security-role-apis" class="ulink" target="_top">role management APIs</a> or defined in the
<a class="xref" href="defining-roles.html#roles-management-file" title="File-based role management">roles file</a>. Either role-mapping method can use
either role management method. For example, when you use the role mapping API,
you are able to map users to both API-managed roles and file-managed roles
(and likewise for file-based role-mappings).</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The PKI, LDAP, Kerberos and SAML realms support using
<a class="xref" href="realm-chains.html#authorization_realms" title="Delegating authorization to another realm">authorization realms</a> as an alternative to role mapping.</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>When <a class="xref" href="anonymous-access.html" title="Enabling anonymous access">anonymous access</a> is enabled, the roles
of the anonymous user are assigned to all the other users as well.</p>
</div>
</div>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Users with no roles assigned will be unauthorized for any action.</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="mapping-roles-api"></a>Using the role mapping API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a>
</h3>
</div></div></div>
<p>You can define role-mappings through the
<a href="security-api-put-role-mapping.html" class="ulink" target="_top">add role mapping API</a>.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="mapping-roles-file"></a>Using role mapping files<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a>
</h3>
</div></div></div>
<p>To use file based role-mappings, you must configure the mappings in a YAML file
and copy it to each node in the cluster. Tools like Puppet or Chef can help with
this.</p>
<p>By default, role mappings are stored in <code class="literal">ES_PATH_CONF/role_mapping.yml</code>,
where <code class="literal">ES_PATH_CONF</code> is <code class="literal">ES_HOME/config</code> (zip/tar installations) or
<code class="literal">/etc/elasticsearch</code> (package installations). To specify a different location,
you configure the <code class="literal">files.role_mapping</code> setting in the
<a href="security-settings.html#ref-ad-settings" class="ulink" target="_top">Active Directory</a>,
<a href="security-settings.html#ref-ldap-settings" class="ulink" target="_top">LDAP</a>, and
<a href="security-settings.html#ref-pki-settings" class="ulink" target="_top">PKI</a> realm settings in
<code class="literal">elasticsearch.yml</code>.</p>
<p>Within the role mapping file, the security roles are keys and groups and users
are values. The mappings can have a many-to-many relationship. When you map roles
to groups, the roles of a user in that group are the combination of the roles
assigned to that group and the roles assigned to that user.</p>
<p>By default, Elasticsearch checks role mapping files for changes every 5 seconds.
You can change this default behavior by changing the
<code class="literal">resource.reload.interval.high</code> setting in the <code class="literal">elasticsearch.yml</code> file. Since
this is a common setting in Elasticsearch, changing its value might effect other
schedules in the system.</p>
<p>While the <em>role mapping APIs</em> is the preferred way to manage role mappings, using
the <code class="literal">role_mappings.yml</code> file becomes useful in a couple of use cases:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
If you want to define fixed role mappings that no one (besides an administrator
with physical access to the Elasticsearch nodes) would be able to change.
</li>
<li class="listitem">
If cluster administration depends on users from external realms and these users
need to have their roles mapped to them even when the cluster is RED. For instance
an administrator that authenticates via LDAP or PKI and gets assigned an
administrator role so that they can perform corrective actions.
</li>
</ol>
</div>
<p>Please note however, that the role_mappings.yml file is provided
as a minimal administrative function and is not intended to cover and be used to
define roles for all use cases.</p>
<div class="important admon">
<div class="icon"></div>
<div class="admon_content">
<p>You cannot view, edit, or remove any roles that are defined in the role
mapping files by using the the role mapping APIs.</p>
</div>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_realm_specific_details"></a>Realm specific details<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a>
</h3>
</div></div></div>
<h5>
<a id="ldap-role-mapping"></a>Active Directory and LDAP realms<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a>
</h5>
<p>To specify users and groups in the role mappings, you use their
<em>Distinguished Names</em> (DNs). A DN is a string that uniquely identifies the user
or group, for example <code class="literal">"cn=John Doe,cn=contractors,dc=example,dc=com"</code>.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>The Elasticsearch security features support only Active Directory security groups.
You cannot map distribution groups to roles.</p>
</div>
</div>
<p>For example, the following snippet uses the file-based method to map the
<code class="literal">admins</code> group to the <code class="literal">monitoring</code> role and map the <code class="literal">John Doe</code> user, the
<code class="literal">users</code> group, and the <code class="literal">admins</code> group to the <code class="literal">user</code> role.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">monitoring: <a id="CO485-1"></a><i class="conum" data-value="1"></i>
  - "cn=admins,dc=example,dc=com" <a id="CO485-2"></a><i class="conum" data-value="2"></i>
user:
  - "cn=John Doe,cn=contractors,dc=example,dc=com" <a id="CO485-3"></a><i class="conum" data-value="3"></i>
  - "cn=users,dc=example,dc=com"
  - "cn=admins,dc=example,dc=com"</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO485-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>The name of a role.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO485-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>The distinguished name of an LDAP group or an Active Directory security group.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO485-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>The distinguished name of an LDAP or Active Directory user.</p>
</td>
</tr>
</table>
</div>
<p>You can use the role-mapping API to define equivalent mappings as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/admins
{
  "roles" : [ "monitoring", "user" ],
  "rules" : { "field" : { "groups" : "cn=admins,dc=example,dc=com" } },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1255.console"></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/basic_users
{
  "roles" : [ "user" ],
  "rules" : { "any" : [
      { "field" : { "dn" : "cn=John Doe,cn=contractors,dc=example,dc=com" } },
      { "field" : { "groups" : "cn=users,dc=example,dc=com" } }
  ] },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1256.console"></div>
<h5>
<a id="pki-role-mapping"></a>PKI realms<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/security/authorization/mapping-roles.asciidoc">edit</a>
</h5>
<p>PKI realms support mapping users to roles, but you cannot map groups as
the PKI realm has no notion of a group.</p>
<p>This is an example using a file-based mapping:</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">monitoring:
  - "cn=Admin,ou=example,o=com"
user:
  - "cn=John Doe,ou=example,o=com"</pre>
</div>
<p>The following example creates equivalent mappings using the API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/admin_user
{
  "roles" : [ "monitoring" ],
  "rules" : { "field" : { "dn" : "cn=Admin,ou=example,o=com" } },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1257.console"></div>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT /_security/role_mapping/basic_user
{
  "roles" : [ "user" ],
  "rules" : { "field" : { "dn" : "cn=John Doe,ou=example,o=com" } },
  "enabled": true
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1258.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="securing-aliases.html">« Granting privileges for indices and aliases</a>
</span>
<span class="next">
<a href="field-and-document-access-control.html">Setting up field and document level security »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>